---
title: "Mastra Class | v1 Migration Guide"
description: "Learn how to migrate Mastra class changes when upgrading to v1."
---

# Mastra Class

The Mastra class has been restructured to restrict top-level imports and replace direct property access with getter methods.

## Changed

### Top-level imports to subpath imports

The main `@mastra/core` index file now only exports `Mastra` and `Config`. All other exports have been moved to subpath imports. This change improves tree-shaking and reduces bundle size by allowing bundlers to eliminate unused code.

To migrate, update all imports from `@mastra/core` to use the appropriate subpath.

```diff
- import { Mastra, Agent, Workflow, createTool } from '@mastra/core';
+ import { Mastra, type Config } from '@mastra/core';
+ import { Agent } from '@mastra/core/agent';
+ import { Workflow } from '@mastra/core/workflows';
+ import { createTool } from '@mastra/core/tools';
```

:::tip[Codemod]

You can use Mastra's codemod CLI to update your code automatically:

```shell
npx @mastra/codemod@beta v1/mastra-core-imports .
```

:::

### `experimental_auth` to `auth`

The experimental auth configuration has been promoted to stable. This change reflects that the auth API is now stable and production-ready.

To migrate, rename the `experimental_auth` key to `auth` in your Mastra configuration.

```diff
  const mastra = new Mastra({
-   experimental_auth: {
+   auth: {
      provider: workos,
    },
  });
```

:::tip[Codemod]

You can use Mastra's codemod CLI to update your code automatically:

```shell
npx @mastra/codemod@beta v1/experimental-auth .
```

:::

### Required `id` parameter for all mastra primitives

All storages, vector stores, agents, workflows, mcpServers, processors, scorers, and tools now require an `id` parameter during initialization. This enables the standardized Mastra API and prevents ID conflicts.

All these primitives also now have `get`, `list`, and `add` functions.

To migrate, add an `id` parameter to all storage and vector store instantiations. When using the same storage/vector class multiple times, ensure each instance has a unique ID.

```diff
- const storage = new LibSQLStore({
-   url: ':memory:',
- });
+ const storage = new LibSQLStore({
+   id: 'my-app-storage',
+   url: ':memory:',
+ });

- const vector = new PgVector({
-   connectionString: process.env.DATABASE_URL,
- });
+ const vector = new PgVector({
+   id: 'my-app-vector',
+   connectionString: process.env.DATABASE_URL,
+ });
```

When using separate instances for different purposes, use descriptive unique IDs:

```diff
  const agentMemory = new Memory({
    storage: new LibSQLStore({
-     url: 'file:./agent.db',
+     id: 'weather-agent-memory-storage',
+     url: 'file:./agent.db',
    }),
  });

  const mastra = new Mastra({
    storage: new LibSQLStore({
+     id: 'mastra-storage',
      url: ':memory:',
    }),
  });
```

### Primitive plural APIs changes from `get<primitives>` to `list<primitive>`

`get*` functions that returned all instances of a primitive have been renamed to `list*` to better reflect their purpose.

```diff
- const agents = mastra.getAgents();
+ const agents = mastra.listAgents();
- const vectors = mastra.getVectors();
+ const vectors = mastra.listVectors();
- const workflows = mastra.getWorkflows();
+ const workflows = mastra.listWorkflows();
- const scorers = mastra.getScorers();
+ const scorers = mastra.listScorers();
- const mcpServers = mastra.getMCPServers();
+ const mcpServers = mastra.listMCPServers();
- const logsByRunId = await mastra.getLogsByRunId({ runId: 'id', transportId: 'id' });
+ const logsByRunId = await mastra.listLogsByRunId({ runId: 'id', transportId: 'id' });
- const logs = await mastra.getLogs('transportId');
+ const logs = await mastra.listLogs('transportId');
```

:::tip[Codemod]

You can use Mastra's codemod CLI to update your code automatically:

```shell
npx @mastra/codemod@beta v1/mastra-plural-apis .
```

:::

### Each primitive has a `getById` and a `get` function

```typescript
mastra.getMCPServer('myServer');          // Works (registry key)
mastra.getMCPServerById('my-mcp-server'); // Works (intrinsic ID)
```

### Tool registration now uses intrinsic IDs

When tools are auto-registered from agents or MCP servers to the Mastra instance, they now use the tool's intrinsic `id` instead of the configuration object key. This prevents collisions when multiple agents/MCP servers have tools with the same configuration key.

To migrate, update any code that references tools by their configuration keys to use the tool's intrinsic ID instead.

```diff
  const agent = new Agent({
    id: 'agent1',
    tools: {
      searchTool: weatherSearchTool,
    },
  });

- mastra.getTool('searchTool');
+ mastra.getTool(weatherSearchTool.id);
```

## Removed

### `memory` property from Mastra class

The `memory` property has been removed from the Mastra class. Memory is now configured at the Agent level rather than globally.

To migrate, move memory configuration from the Mastra constructor to individual Agent constructors.

```diff
- const mastra = new Mastra({
-   memory: new Memory({
-     storage: libsqlStore,
-     vector: libsqlVector,
-     embedder: fastembed,
-   }),
- });
- 
- const agent = new Agent({
-   name: 'my-agent',
- });

+ const mastra = new Mastra({
+   // memory removed from here
+ });
+ 
+ const agent = new Agent({
+   name: 'my-agent',
+   memory: new Memory({
+     storage: libsqlStore,
+     vector: libsqlVector,
+     embedder: fastembed,
+   }),
+ });
```
